/*
 * Copyright (C) 2011 JiangHongTiao <jjurco.sk_gmail.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package sk.lieskove.jianghongtiao.websearch.service;

import java.net.URL;

/**
 * Interface encapsulate methods for searching in search engines. Class which will
 * implement this interface should handle correctly these methods. If search engine 
 * does not provide such functionality, class should print warning to error console 
 * during initialization. 
 * 
 * Date of create: Jul 11, 2011
 *
 * @author JiangHongTiao <jjurco.sk_gmail.com>
 * @version 2011.0711
 */
public interface SearchQuery {
    
    /**
     * add word to search query. Search engines will search for this word. 
     * @param word word for search query
     */
    public void addWord(String word);
    /**
     * Add exact word to search query. Search engine will match word precisely 
     * as it was typed. Without any synonyms or stemming.
     * @param word exact word to search.
     */
    public void addExactWord(String word);
    /**
     * Add exact phrase to search query. Search engine will search for a set of 
     * words in that exact order without any change.
     * @param phrase Set of words in specific order 
     */
    public void addExactPhrase(String phrase);
    
    /**
     * Search engine will search for one of several words.
     * @param choices words for one of them we want to search
     */
    public void addChoices(String ... choices);
    /**
     * search for word and also for synonyms of that word. Currently supported only by google!
     * @param synonym word for which we want to search also in synonyms
     */
    public void addSynonym(String synonym);
    /**
     * search is restricted for one site
     * @param site site URL for which we want to restrict search
     */
    public void addSearchInSite(URL site);
    /**
     * Search in title of page
     * @param inTitleString word which have to occur in title of the page
     */
    public void addSearchInTitle(String inTitleString);
    /**
     * Searched word have to occur in URL of the page
     * @param inUrlString word which have to occur in the URL of the page
     */
    public void addSearchInUrl(String inUrlString);
    /**
     * Search only for documents with specified Filetype
     * @param extension extension of the file restriction
     */
    public void addFiletype(String extension);
    
    /**
     * Find only documents which does not contains this word. Be careful, when you
     * exclude word from the search. Then you have to specify also another word for which
     * you do search! Without that searched word search engines may return empty
     * result set!
     * @param word search for documents which does not contains this word
     */
    public void addExcludeWord(String word);
    /**
     * Search engine will search for words but exclude from results site specified 
     * by this method
     * @param site URL of the server which will be excluded from search results
     */
    public void addExcludeSearchInSite(URL site);
    
    /**
     * get base query without modifiers
     * 
     * @return base query without any modifier. Only words added by method 
     * addWord will be returned
     */
    public String getBaseQuery();
    
    /**
     * get full query for search engine (google, yahoo, bing). All words or 
     * phrases will be added. 
     * 
     * @return full query for search
     */
    public String getFullQuery();
    
    /**
     * remove all parameters to construct new query
     */
    public void resetQuery();
    
}
